home *** CD-ROM | disk | FTP | other *** search
/ MacFormat 1994 October / macformat-005.iso / Shareware City / Developers / xlispmac / lisp / STEPPER.DOC < prev    next >
Encoding:
Text File  |  1994-05-28  |  5.1 KB  |  137 lines  |  [TEXT/ALFA]
  1. [Tom Almy comments: 
  2.   The program did not correctly handle RETURN (as reported by Martin Glanvill,
  3.   mcg@waikato.ac.nz). In the process of fixing the the problem it was
  4.   discovered that the nexting printout did not work properly for all return,
  5.   return-from, throw, and many cases of go. This version has been fixed for
  6.   hopefully all of the above, although go will still not produce proper
  7.   printout if the jump is outside the most enclosing tagbody, and the tag
  8.   arguments of catch/throw must either be symbols or quoted symbols.
  9.   I'm making no attempt here to correctly handle tracing of unwind-protect, 
  10.   either!
  11.  
  12.   Tom Almy  5/92
  13. ]
  14.  
  15.  
  16. This is the latest version of my stepper.   I posted an early version of
  17. it about a year ago;  this differs from the old one as follows:
  18.   o  May change both print depth and print length of forms
  19.     (old version only allowed print depth to be changed)
  20.   o  Uses 'get-key' for user input, (in particular this is PC specific,
  21.     I only use XLISP on PC's;  I use KCL on real computers)
  22.   o  New 'u' command (execute until enclosing form returns)
  23.   o  New 'r' command (use a given expression as the return value
  24.     for the current form)
  25.   o  Correct handling of '(go label)' statements
  26.   o  Uses *debug-io* to determine output stream
  27.  
  28. The attached listing is a step debugger inspired by the "step.lsp"
  29. stepper included with XLISP 2.1, originally written by Jonathan Engdahl
  30. (jengdahl on BIX).  This version has the ability to set/reset
  31. breakpoints, and a few bells and whistles.
  32.  
  33. To invoke the stepper:
  34.     (step (form with args))
  35.  
  36. The stepper will stop and print every form, then wait for user input.
  37. Forms are printed compressed, i.e. to a depth and length of 3.  This
  38. may be changed by assigning the desired depth and length values to
  39. *pdepth* and *plen* before invoking the stepper, or from within the
  40. stepper via the . and # commands.
  41.  
  42. For example, suppose you have the following defined:
  43.  
  44. (defun fib (n)
  45.   (if (or (eql n 1) (eql n 2))
  46.       1
  47.       (+ (fib (- n 2)) (fib (- n 1)))))
  48.  
  49. Then (step (fib 4)) will produce the following:
  50.  
  51. 0 >==> (fib 4)
  52.  1 >==> (if (or (eql n 1) (eql n 2)) 1 ...) :
  53.  
  54. The colon is the stepper's prompt.  For a list of commands, type h.
  55. this produces:
  56.  
  57. Stepper Commands
  58. ----------------
  59.  n or space - next form
  60.  s or <cr>  - step over form
  61.  f FUNCTION - go until FUNCTION is called
  62.  b FUNCTION - set breakpoint at FUNCTION
  63.  b <list>   - set breakpoint at each function in list
  64.  c FUNCTION - clear breakpoint at FUNCTION
  65.  c <list>   - clear breakpoint at each function in list
  66.  c *all*    - clear all breakpoints
  67.           g - go until a breakpoint is reached
  68.           u - go up; continue until enclosing form is done
  69.           w - where am I? -- backtrace
  70.           t - toggle trace on/off
  71.           q - quit stepper, continue execution
  72.           p - pretty-print current form (uncompressed)
  73.           e - print environment
  74.    x <expr> - execute expression in current environment
  75.    r <expr> - execute and return expression
  76.        # nn - set print depth to nn
  77.        . nn - set print length to nn
  78.           h - print this summary
  79.  
  80. Breakpoints may be set with the b command.  You may set breakpoints at
  81. one function, e.g. b FOO<cr> sets a breakpoint at the function FOO,
  82. or at various functions at once, e.g. b (FOO FIE FUM)<cr> sets
  83. breakpoints at the functions FOO, FIE, and FUM.  Breakpoints are cleared
  84. with the c command in an analogous way.  Furthermore, a special form of
  85. the c command, c *all* <cr>, clears all previously set breakpoints.
  86. Breakpoints are remembered from one invocation of step to the next, so
  87. it is only neccessary to set them once in a debugging session.
  88.  
  89. The g command causes execution to proceed until a breakpoint is reached,
  90. at which time more stepper commands can be entered.
  91.  
  92. The f command sets a temporary breakpoint at one function, and causes
  93. execution to proceed until that function is called.
  94.  
  95. The u command continues execution until the form enlosing the current
  96. form is done, then re-enters the stepper.
  97.  
  98. The w command prints a back trace.
  99.  
  100. The q command quits and causes execution to continue uninterrupted.
  101.  
  102. Entry and exit to functions are traced after a g, f, u, or q command.  To
  103. turn off tracing, use the t command which toggles the trace on/off.
  104. Also, with trace off, the values of function parameters are not printed.
  105.  
  106. The s command causes the current form to be evaluated.
  107.  
  108. The n command steps into the current form.
  109.  
  110. The . and # commands change the compression of displayed forms.  E.g. in the
  111. previous example:
  112.  
  113.  1 >==> (if (or (eql n 1) (eql n 2)) 1 ...) : . 2
  114.  1 >==> (if (or (eql n ...) ...) ...) :
  115.  
  116. changes the print length to 2, and
  117.  
  118.  1 >==> (if (or (eql n ...) ...) ...) : # 2
  119.  1 >==> (if (or #\# ...) ...) :
  120.  
  121. changes the print depth to 2.
  122.  
  123. To print the entire form use the p command, which pretty-prints the
  124. entire form.
  125.  
  126. The e command causes the current environment to be printed;
  127.  
  128. The x command causes an expression to be executed in the current
  129. environment.  Note that this permits the user to alter values while
  130. the program is running, and may affect execution of the program.
  131.  
  132. The r command causes the value of the given expression to be returned,
  133. i.e. makes it the return value of the current form.
  134.  
  135. Enjoy,
  136.       Ray
  137.